.\" $Id: PAPI_get_virt_cyc.3,v 1.9 2004/10/04 02:16:26 jthomas Exp $
.TH PAPI_get_virt_cyc 3 "September, 2004" "PAPI Programmer's Reference" "PAPI"

.SH NAME
PAPI_get_virt_cyc \- get virtual time counter value in clock cycles
.LP
PAPI_get_virt_usec \- get virtual time counter values in microseconds

.SH SYNOPSIS
.B C Interface
.nf
.B #include <papi.h>
.BI "long_long PAPI_get_virt_cyc(void);"
.BI "long_long PAPI_get_virt_usec(void);"
.fi
.B Fortran Interface
.nf
.B #include "fpapi.h"
.BI PAPIF_get_virt_usec(C_LONG_LONG\  time)
.BI PAPIF_get_virt_cyc(C_LONG_LONG\  virt_cyc)
.fi

.SH DESCRIPTION
Both of these functions return the total number of virtual units from
some arbitrary starting point. Virtual units accrue every time the
process is running in user-mode on behalf of the process. Like the
real time counters, these are guaranteed to exist on every platform
PAPI supports. However on some platforms, the resolution can be as bad
as 1/Hz as defined by the operating system.

.SH ERRORS
The functions returns 
.B PAPI_ECNFLCT 
if there is no master event set.
This will happen if the library has not been initialized, or for threaded
applications, if there has been no thread id function defined by the 
.BR PAPI_thread_init\  function.

For threaded applications, if there has not yet been any thread
specific master event created for the current thread, and if the
allocation of such an event set fails, the call will return
.BR PAPI_ENOMEM or PAPI_ESYS .

.SH EXAMPLE
.LP
.nf
.if t .ft CW
s = PAPI_get_virt_cyc();
your_slow_code();
e = PAPI_get_virt_cyc();
printf("Process has run for cycles: %lld\en",e-s);
.if t .fr P
.fi

.SH BUGS
These functions have no known bugs.

.SH SEE ALSO
.BR PAPI_library_init "(3), "
.BR PAPI_get_real_usec "(3), " 
.BR PAPI_get_real_cyc "(3), "
.BR PAPI "(3), " 
.BR PAPIF "(3)" 
